home *** CD-ROM | disk | FTP | other *** search
/ Disc to the Future 2 / Disc to the Future Part II Programmer's Reference (Wayzata Technology)(6013)(1992).bin / MAC / THINKC / 4_0 / UUPC3 / (OLD_SUP / README.POR < prev    next >
Text File  |  1988-03-10  |  13KB  |  302 lines
  1. uupc Porting Information     August 3, 1987      uupc Development
  2.  
  3.  
  4. This writeup is aimed at programmers intending to port uupc to
  5. machines and operating systems which it don't currently run on.
  6. If you only want to install uupc on a system where a uupc port
  7. exists, this writeup might also provide some insights to the
  8. internal working of uupc and make the installation of uupc on
  9. your machine a more interesting task.
  10.  
  11. Since I did part of the IBM-PC/MS-DOS port for uupc, what I will
  12. describe here is actually closely related to the structure of
  13. this particular port.  (I also did part of the port of uupc's
  14. mailer to AIX (SVR1) on the RT-PC.)  What is shown here is *by no
  15. mean* the only way things could be done, it's just some tips and
  16. hints that I can think of after doing one-and-a-half port of
  17. uupc.
  18.  
  19. The purpose of this writeup is to try to make the life of
  20. programmers doing uupc ports for other machines/operating systems
  21. easier.  However, the best sources of information on how new
  22. ports should be done is still by reading the system-dependent
  23. code of the existing uupc ports.  (This is how I learnt how to do
  24. my ports.)  It would also be useful to have a listing of the
  25. system-dependent code of the IBM-PC/DOS port handy while reading
  26. this writeup.
  27.  
  28.  
  29. To compile uupc, the C compiler and linker on your system must be
  30. able to differentiate between upper and lower cases in external
  31. names.
  32.  
  33. The C run-time support on your system should use '\n' as line
  34. separator for *text* files.  If your system uses other sequences
  35. or methods to delimit text file lines, the C run-time support
  36. must perform the appropriate translation functions for mapping in
  37. both directions when a file is opened in text mode.
  38.  
  39. In order to port uupc to a new machine/operating system, you have
  40. to come up with a new version of six system-dependent files in
  41. the the "local" directory.  The names of these six files in the
  42. local directory are host.h, host.c, mlib.c, ulib.c, ndir.h and
  43. ndir.c.
  44.  
  45. Note that theses files could in turn #include other *.c and *.h
  46. files if you wish to separate the system-dependent code into more
  47. small files.  The important thing here is that they must
  48. collectively provide the same set of routines, global variables,
  49. and environment to the common code.
  50.  
  51. What should be contained in these six files are describe below:
  52.  
  53.  
  54. host.h - Host dependent file virtual #included everywhere else.
  55.  
  56.    Almost every file in both the common and host-dependent code
  57.    include this header file.  So it should contains all the
  58.    #includes, #defines, and externs that everybody would need.
  59.  
  60.    Parts of the uupc common code assume Berkeley-style index()
  61.    and rindex(), so if your system supports only SysV-style
  62.    strchr() and strrchr(), they need to mapped using #define
  63.    here.
  64.  
  65.    Declarations for "library" routines in host.c, mlib.c and
  66.    ulib.c should also be make here to made them known to the rest
  67.    of the world.  However, declaractions for the directory
  68.    scanning routines should be put into ndir.h instead.
  69.  
  70.    If your system requires that text file and binary fiies be
  71.    opened differently, you should map the name 'FILEMODE' into
  72.    'filemode' with a #define here.  Otherwise, 'FILEMODE' should
  73.    be mapped to the null string.
  74.  
  75.  
  76. host.c - Generic main program and library routines for both parts.
  77.  
  78.    This file includes a generic main program that simply starts
  79.    up and call the procedure MAIN.  More importantly, the
  80.    definition of all the library routines that are needed by both
  81.    uu and mail are also here.
  82.  
  83.    This generic main program is used to start up both uu and
  84.    mail, by having the preprocessor symbol MAIN #defined to
  85.    different procedure names in the files which include host.c.
  86.    This generic main program should perform all the necessary
  87.    start up and wrap up functions as required by the host
  88.    operating system and call the routine MAIN while the host
  89.    environment is established.
  90.  
  91.    If the preprocessor symbol CWDSPOOL is #defined by the file
  92.    that #includes host.c, the main program should change the
  93.    current working directory to the spooling directory before
  94.    calling MAIN, and switch back to the orginal directory after
  95.    MAIN had returned.
  96.  
  97.    The following are the other routines residing in host.c and
  98.    used by the others parts of both uu and mail:
  99.  
  100.    importpath - A deterministic function which maps a canonical
  101.       file name to a local file name.  This function must be
  102.       deterministic (i.e. always return the same local name when
  103.       given the same canonical name) because it is used on each
  104.       canonical file name several times in various part of the
  105.       code to obtain the corresponding local file name.
  106.  
  107.       A canonical file name has the same format as a UNIX
  108.       pathname, and the format of a local file name is defined by
  109.       your local file system.
  110.  
  111.       This function should at least preserve the first 6 and last
  112.       2 characters of the canonical file name, since this parts
  113.       of the canonical file name usually contain the site name
  114.       and the sequence number, which is critical to the
  115.       successful operation of uupc.
  116.  
  117.       Perferably the last 4 characters of the canonical file name
  118.       should be perserved, since that is the number of digits in
  119.       the sequence number, but if that is not possible, an
  120.       attempt should be made to preverse the last 3 characters
  121.       before resorting to only preserve the last 2 characters.
  122.       (With only the last 2 characters preserved, the spool file
  123.       sequence number cycle will become only 100 before it goes
  124.       around again.)
  125.  
  126.    mkfilename - Build a local path name out of a given local
  127.       directory path and local base name pair.  It usually just
  128.       concatenates the two parts together with the local system's
  129.       directory path separator between them.
  130.  
  131.    loadenv - Retrieve certain configuration parameters from the
  132.       user's "environment" and make them available to the
  133.       program.  This involves filling in the appropriate global
  134.       (char *) variables to point to the appropriate strings
  135.       which contains the character value of the desired
  136.       configuration parameters.
  137.  
  138.    If your system requires the differentiation of text file and
  139.    binary files, you should also supply the following routine.
  140.  
  141.    filemode() - If this routine is passed the character 't' as
  142.       parameter, any subsequently opened file in the program
  143.       should be opened in text mode.  Similarly, if the parameter
  144.       is the character 'b', all subsequently opened file should
  145.       be opened in binary mode.
  146.  
  147.  
  148. mlib.c - Library of routines used only by the mail part.
  149.  
  150.    Currently there is only one routine in this library.
  151.  
  152.    get_one - Wait for a single character to be typed on the
  153.       console keyboard and return to the caller with the
  154.       character read as soon as it is pressed.  It short, this is
  155.       a routine that detects and returns a keypress.
  156.  
  157.       This routine is used when you reach the bottom of a page
  158.       while paging through your mail.
  159.  
  160.       The single character read by this routine should not be
  161.       echoed to the console screen.
  162.  
  163.  
  164. ulib.c - Library of routines used only by the uu part.
  165.  
  166.    login - The logger which verifies logins and passwords for
  167.       incoming UUCP connections.  You only need to have this
  168.       routine functional if you plan to ever run your node in
  169.       slave mode.  i.e. Waiting on the phone line for other nodes
  170.       to call you to make UUCP connections.
  171.  
  172.    shell - Perform an UNIX command sent from a remote site via
  173.       uux.  To support incoming remote mail you need to emulate
  174.       the UNIX 'rmail' command, which can be easily done using
  175.       the pcmail package (compiled as rmail) which is part of
  176.       this uupc distribution.  If you want to also support
  177.       incoming USENET news-feeds, the UNIX 'rnews' command will
  178.       need to be supported as well.
  179.  
  180.       If your system is capable of invoking another program
  181.       within a program, you might want to dispatch rmail and
  182.       rnews as a separate program here.  Otherwise, you might
  183.       need to compile, or link, them into uu as routines.
  184.  
  185.    sleep - Wait a specified number of seconds in real-time.  You
  186.       could either use a busy wait loop or a timer alarm here,
  187.       depending on if your system has other (e.g. background)
  188.       jobs competing for CPU time at the same time.  On mutli-
  189.       tasking or multi-users systems, you would likely *not* want
  190.       to busy wait even if that's easier to implement.
  191.  
  192.    The rest of this library consists of routines to deal with the
  193.    communications line (serial port).
  194.  
  195.    openline - Open a communications line as the active line.  The
  196.       name of the serial line device and the speed to open the
  197.       line at are *both* specified as (char *) type parameters.
  198.       These value are just the corresponding values in the
  199.       systems file entry of the site being called.
  200.  
  201.    sread - Read a specified number of bytes from the active
  202.       serial line and return with *no* input characters consumed
  203.       *if* the specified number of bytes is not available after
  204.       the specified timeout period.  This is basically a non-
  205.       blocking read that waits up to an user-specified amount of
  206.       time before returning.
  207.  
  208.    swrite - Write a specified number of bytes out to the active
  209.       serial line.  No timeout mechanism needs to be provided by
  210.       this routine.
  211.  
  212.    closeline - Close the active communications line.
  213.  
  214.    SIOSpeed - Change the line speed of the active communications
  215.       line on-the-fly.  The new line speed is given as (char *)
  216.       rather than (int).  Note the mixed-case nature of this
  217.       routine name.
  218.  
  219.  
  220. ndir.h - Header file for the directory scanning routines.
  221.  
  222.    At least the following needs to be defined in this file.
  223.  
  224.    -- The constant 'MAXNAMLEN' declared with "#define".  This is
  225.       the maximum length of a file name in your system.  Note
  226.       that a file name does not include a directory path prefix,
  227.       it is only the maximum length of a file name within a
  228.       directory.
  229.  
  230.    -- The structure 'direct' declared with "struct".  This
  231.       structure is a public data structure and its fields are
  232.       examined directly by uu, so your declaration needs to
  233.       provide at least the following fields:
  234.  
  235.       struct direct {
  236.          short d_reclen;
  237.          short d_namlen;
  238.          char  d_name[MAXNAMLEN + 1];
  239.       };
  240.  
  241.       d_reclen is the length of the structure minus the size of
  242.       the unused portion of d_name at the end of the structure.
  243.  
  244.       d_namelen is strlen(d_name).
  245.  
  246.       d_name is the name of the next file in the scan, with a
  247.       terminating '\0'.
  248.  
  249.       It is important for the structure 'direct' to be defined
  250.       using "struct" insted of "typedef".
  251.  
  252.    -- The type 'DIR' declared with "typedef".  This is a private
  253.       structure used by the ndir routines and should contain all
  254.       the static data related to a single invocation of the ndir
  255.       routines.
  256.  
  257.       It is important for 'DIR' to be defined using "typedef"
  258.       instead of "struct".  (Note this is the *reverse* of the
  259.       structure 'direct' above.)
  260.  
  261.    -- The routines opendir(), readdir(), and closedir().  Which
  262.       opens a specified directory, read the next file entry from
  263.       an opened directory, and close an opened directory,
  264.       respectively.
  265.  
  266.  
  267. ndir.c - "Berkeley-style" directory scanning routines.
  268.  
  269.    This file contains a set of routines similar in functions to
  270.    the Berkeley-style directory scanning routines.  These
  271.    routines are used only by uu, not mail, and only the
  272.    opendir(), readdir(), and closedir() routines are used, and
  273.    therefore need to be implemented.
  274.  
  275.    Eventhough the ndir routines should be capable of mutliple
  276.    concurrent invocations using separate (DIR *)'s, uu only uses
  277.    one invocation of it at a time.
  278.  
  279.    If your system's file name is mono-case, then your readdir()
  280.    routine should always return the file name field (d_name) in
  281.    all lowercase.
  282.  
  283.  
  284. Any questions about porting uupc to other machines/operating
  285. systems, and comments and suggestions about this writeup should
  286. be directed to one of the e-mail addresses listed at the end of
  287. this file.
  288.  
  289. If you do decide to start porting uupc to a new machine/operating
  290. system, please drop us a line as well.  We might even be able to
  291. save each other some duplicated efforts!
  292.  
  293.  
  294. UUCP: {seismo,ihnp4!alberta,uw-beaver,uunet}!ubc-vision!van-bc!uupc
  295. Internet: uupc@van-bc.UUCP
  296. -------
  297.  
  298.  
  299. --
  300. {ihnp4!alberta!ubc-vision,uunet}!van-bc!Stuart.Lynne Vancouver,BC,604-937-7532
  301.  
  302.